Export and import data derived from dynamic flex fields

You can use SNX (not GNX) to import and export data derived from dynamic flex fields (to import and export customization metadata, you use XML; for details, see Export an XML file (on page 1) and Generic Entity XML Importer form (on page 1)). For this purpose, the schema definition file snx-types.xsd includes the element custom-dynamic-flex-fields, as shown in the following code example:

<xs:complexType name="tCustomDynamicFlexFields">

<xs:annotation>

<xs:documentation>Describes the custom dynamic flex fields that are added on an N4 Entity.

</xs:documentation>

</xs:annotation>

<xs:sequence>

<xs:element name="equipment" type="argo:tUnitEquipment" minOccurs="0" maxOccurs="20"/>

.....

<xs:element name="custom-dynamic-flex-fields" type="argo:tCustomDynamicFlexFields" minOccurs="0" maxOccurs="1"/>

</xs:sequence>

</xs:complexType>

N4 embeds any custom dynamic fields in the base entity's definition. This ensures that they are processed in the same transaction as the parent instance. In an exported data file, the code looks as follows:

<?xml version="1.0" encoding="UTF-8"?>

<argo:snx xmlns:argo="http://www.navis.com/argo" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xsi:schemaLocation="http://www.navis.com/argo snx.xsd http://www.navis.com/argo ">

.....

<unit id="TFFV9588002" category="EXPORT" restow="NONE" transit-state="YARD" freight-kind="FCL" unique-key="TFFV9588002" line="POPEYE">

<equipment eqid="TFFV9588002" type="2200" created-by="-system-" created-date="2010-12-24T23:44:07" class="CTR" life-cycle-state="ACT" role="PRIMARY">

<physical has-wheels="N" height-mm="2591" is-insulated="N" is-permanently-out-of-service="N" iso-group="GP" length-mm="6068" material="UNKNOWN" strength-code="TB" tare-weight-kg="1900.0" width-mm="2438"/>

<ownership owner="POPEYE" operator="POPEYE"/>

<restrictions is-open="N" is-unsealable="N" no-top_stow-if-empty="N" no-top-stow-if-full="N" out-of-gauge-ok="N" safe-weight-kg="0.0" stow-above-deck="N" stow-below-deck="N" uses-accessories="N"/>

<transponder/>

<damages/>

</equipment>

<position loc-type="YARD" location="YRD1111"/>

<routing pol="OAK" pol-name="United States" pod-1="LYT" pod-1-name="New Zealand" origin="OAK">

<carrier direction="IB" qualifier="DECLARED" mode="TRUCK"/>

<carrier direction="IB" qualifier="ACTUAL" mode="TRUCK"/>

<carrier direction="OB" qualifier="DECLARED" mode="VESSEL" id="VES002"/>

<carrier direction="OB" qualifier="ACTUAL" mode="VESSEL" id="VES002"/>

</routing>

<booking id="BKGSEE"/>

<contents weight-kg="1900.0"/>

<unit-etc category="EXPORT" line="POPEYE"/>

<timestamps time-in="2010-12-24T23:44:07" time-last-move="2010-12-24T23:44:07"/>

<non-move-history>

<event id="UNIT_CREATE" note="snx" time-event-applied="2010-12-24T23:44:07" user-id="snx:-system-" is-billable="N"/>

<event id="UNIT_ACTIVATE" time-event-applied="2010-12-24T23:44:07" user-id="snx:-system-" is-billable="N"/>

</non-move-history>

<custom-dynamic-flex-fields>

<custom-dynamic-flex-field name="unitCustomDFFString1" value="unitcdff1_value"/>

      <custom-dynamic-flex-field name="unitCustomDFFString2" value="unitcdff2_value"/>

</custom-dynamic-flex-fields>

</unit>

</argo:snx>

N4 handles SNX import and export using code extensions. Therefore, as part of importing or exporting dynamic flex fields for an entity, you must create code extensions of type ENTITY_CUSTOM_DYNAMIC_FLEX_FIELDS_EXPORTER and ENTITY_CUSTOM_DYNAMIC_FLEX_FIELDS_EXPORTER.

N4 supports export of dynamic flex fields for all entities. However, you can only import dynamic flex fields for the following entities:

To export dynamic flex fields:

1. In the Code Extensions view (on page 1), create a code extension of type ENTITY_CUSTOM_DYNAMIC_FLEX_FIELDS_EXPORTER named <EntityName>SnxExporter, such as UnitSnxExporter.

The code extension must extend the class DefaultCustomDynamicFlexFieldsExporter and implement or use the default methods of the interface ECustomDynamicFlexFieldsExporter. For example:

public interface ECustomDynamicFlexFieldsExporter extends EArgoInterceptor {

void init(String inEntityName);

void getCustomDynamicMetafieldIds(Set<MetafieldId> inOutInputSet);

void createCustomDynamicFlexFieldsElement(Element inOutParentElement, Map inResultMap);

where:

• getCustomDynamicMetafields(Set<MetafieldId> inOutInputSet) provides the set of dynamic metafield IDs you want to export.

• createCustomDynamicFlexFieldsElement composes a new jdom element and adds it to the parent element.

The following groovy code demonstrates the usage of these two methods, addressing a dynamic field of the Unit entity from the UnitFacilityVisit entity (ufvUnit.customFlexFields.unitCustomDFF_SNX_IMPORTER_TEST_FIELD).

import com.navis.argo.business.snx.DefaultCustomDynamicFlexFieldsExporter;

import com.navis.framework.metafields.MetafieldId

import com.navis.framework.metafields.MetafieldIdFactory

import org.jdom.Element

import org.jdom.Namespace

class UnitSnxExporterTest extends DefaultCustomDynamicFlexFieldsExporter {

public void getCustomDynamicMetafieldIds(Set<MetafieldId> inOutMetafieldIdSet) {

    Set<MetafieldId> dynamicMetafieldIds = getCustomDynamicMetafieldIds();

        if (inOutMetafieldIdSet == null) {

            inOutMetafieldIdSet = dynamicMetafieldIds;

        } else {

            inOutMetafieldIdSet.addAll(dynamicMetafieldIds);

        }

  }

  private Set<MetafieldId> getCustomDynamicMetafieldIds() {

    Set<MetafieldId> dynamicMetafieldIds = new HashSet();

    dynamicMetafieldIds.add(MetafieldIdFactory.valueOf("ufvUnit.customFlexFields.unitCustomDFF_SNX_IMPORTER_TEST_FIELD"));

    return dynamicMetafieldIds;

  }

  public void createCustomDynamicFlexFieldsElement(Element inOutParentElement, Map inResultMap) {

        Namespace namespace = inOutParentElement.getNamespace();

        MetafieldId fieldId = MetafieldIdFactory.valueOf("ufvUnit.customFlexFields.unitCustomDFF_SNX_IMPORTER_TEST_FIELD");

        String value = (String) inResultMap.get(fieldId);

        if (value == null) {

          value = "empty";

        }

        Element dynamicFieldsElement  = new Element(DefaultCustomDynamicFlexFieldsExporter.CUSTOM_DYNAMIC_FLEX_FIELDS_ELEMENT, namespace);

        Element dynamicFieldElement  = new Element(DefaultCustomDynamicFlexFieldsExporter.CUSTOM_DYNAMIC_FLEX_FIELD_ELEMENT, namespace);

        dynamicFieldElement.setAttribute(DefaultCustomDynamicFlexFieldsExporter.NAME_ATTRIBUTE,
"customFlexFields.unitCustomDFF_SNX_IMPORTER_TEST_FIELD", namespace);

        dynamicFieldElement.setAttribute(DefaultCustomDynamicFlexFieldsExporter.VALUE_ATTRIBUTE, translateToString(value), namespace);

        dynamicFieldsElement.addContent(dynamicFieldElement);

        inOutParentElement.addContent(dynamicFieldsElement);

  }

}

2. In the view that includes the dynamic flex field you created, select an entity and click Actions Export SNX File. See also Export SNX File.

3. In the SNX output file, make sure the following tag is included:

<custom-dynamic-flex-fields>

<custom-dynamic-flex-field name="customFlexFields.<EntityName>CustomDFF_<FieldName>" value="your value" />

  </custom-dynamic-flex-fields>

To import dynamic flex fields:

1. In the Code Extensions view (on page 1), create a code extension of type ENTITY_CUSTOM_DYNAMIC_FLEX_FIELDS_IMPORTER named <EntityName>SnxImporter, such as UnitSnxImporter.

The code extension must extend the class DefaultCustomDynamicFlexFieldsImporter and implement or use the default methods of the interface ECustomDynamicFlexFieldsImporter.

2. Import an XML file (Administration DBA Import SNX File) that includes the dynamic flex fields specified in the code extension. See also Import data.

For testing purposes, you can use the file created when exporting dynamic flex fields.